<html><head><TITLE>PtrVec</TITLE></head>
 <body text="#111111" bgcolor="#FFFFFF" link="#333399" vlink="#663366" alink="#CC0000">

<h3>&nbsp;&nbsp;
<font color="#7700EE">HTM SpatialIndex Class Reference</font>
</h3>
<img SRC="rule.gif" >


<H2><A HREF ="#DOC.DOCU" > <IMG BORDER=0 SRC=down.gif></A> template <class T>   class  PtrVec  </H2><BLOCKQUOTE>
Dynamic array of pointers

This is a template for a dynamic array of pointers
</BLOCKQUOTE>
<hr>

<DL>
<TABLE BORDER>
<DT><h3>Public Fields</h3><DD><TR><TD VALIGN=top><A HREF="#DOC.20.23"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>increment_</B> <br>
<I> linear growth increment</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.24"> <IMG BORDER=0 SRC=icon1.gif></A> T** </TD><TD><B>vector_</B> <br>
<I> dynamic array of pointers</I>
</TD></TR></TABLE><TABLE BORDER>
<DT><h3>Public Methods</h3><DD><TR><TD VALIGN=top><A HREF="#DOC.20.15"> <IMG BORDER=0 SRC=icon1.gif></A> </TD><TD><B>~PtrVec</B> ( void )<br>
<I>Destructor</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.1"> <IMG BORDER=0 SRC=icon1.gif></A> </TD><TD><B>PtrVec</B> ( bool <!2><A HREF="PtrVec.html#DOC.20.22">internal</A>=true, size_t capacity=0, size_t increment=0 )<br>
<I>Default constructor</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.2"> <IMG BORDER=0 SRC=icon1.gif></A> </TD><TD><B>PtrVec</B> ( const <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>&, bool <!2><A HREF="PtrVec.html#DOC.20.13">internalize</A> = true )<br>
<I>Copy constructor</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.3"> <IMG BORDER=0 SRC=icon1.gif></A> <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>& </TD><TD><B>copy</B> ( const <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>&, bool <!2><A HREF="PtrVec.html#DOC.20.13">internalize</A> )<br>
<I>Copy method</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.4"> <IMG BORDER=0 SRC=icon1.gif></A> <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>& </TD><TD><B>operator =</B> ( const <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A> &obj )<br>
<I>Assignment/copy operator</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.16"> <IMG BORDER=0 SRC=icon1.gif></A> const  T*& operator </TD><TD><B>()</B> ( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> ) const <br>
<I>Efficient array operator (const version): no bounds checking</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.17"> <IMG BORDER=0 SRC=icon1.gif></A> T*& operator </TD><TD><B>()</B> ( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> )<br>
<I>Efficient array operator (non-const version): no bounds checking</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.18"> <IMG BORDER=0 SRC=icon1.gif></A> const  T*& </TD><TD><B>operator []</B> ( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> ) const <br>
<I>Bounds-checking array operator (const version): throws sxBoundsError</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.19"> <IMG BORDER=0 SRC=icon1.gif></A> T*& </TD><TD><B>operator []</B> ( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> )<br>
<I>Bounds-checking array operator (non-const version): throws sxBoundsError</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.5"> <IMG BORDER=0 SRC=icon1.gif></A> T*& </TD><TD><B>at</B> ( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> )<br>
<I>Bounds-adjusting array operator</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.20"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>length</B> ( void ) const <br>
<I>Returns current occupied length of array</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.6"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>entries</B> ( void ) const <br>
<I>Return the number of non-NULL entries in vector</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.7"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>append</B> ( T* )<br>
<I>Append: efficiently insert given element at end of array</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.8"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>insert</B> ( size_t count, size_t offset = 0 )<br>
<I>Insert new array elements</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.21"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>nextEmpty</B> ()<br>
<I>Return the index of the next available empty slot</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.9"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>add</B> ( T* )<br>
<I>Add a new array element in the first available empty slot</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.10"> <IMG BORDER=0 SRC=icon1.gif></A> int </TD><TD><B>index</B> ( const T* )<br>
<I>Return the index of the given element</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.11"> <IMG BORDER=0 SRC=icon1.gif></A> size_t </TD><TD><B>cut</B> ( size_t count, size_t offset = 0 )<br>
<I>Remove array elements</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.12"> <IMG BORDER=0 SRC=icon1.gif></A> void </TD><TD><B>remove</B> ( size_t offset )<br>
<I>Removes the element specified by offset</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.13"> <IMG BORDER=0 SRC=icon1.gif></A> void </TD><TD><B>internalize</B> ( void )<br>
<I>Replace external pointers with internal
copies of the referenced objects</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.14"> <IMG BORDER=0 SRC=icon1.gif></A> void </TD><TD><B>externalize</B> ( void )<br>
<I>Change status of pointers to external</I>
</TD></TR><TR><TD VALIGN=top><A HREF="#DOC.20.22"> <IMG BORDER=0 SRC=icon1.gif></A> bool </TD><TD><B>internal</B> ( void ) const <br>
<I>internal method: returns true if the pointers are internal</I>
</TD></TR></TABLE></DL>
<A NAME="DOC.DOCU">
<hr>
 <h2> Documentation </h2>
<BLOCKQUOTE>
Dynamic array of pointers

This is a template for a dynamic array of pointers.  The design is
very similar to the general-purpose version, ValVec, but
specialized according to the memory management issues peculiar to
storing pointers.  This version uses nil as the fill value, which
cannot be customized or disabled.  By default, the cut method uses
the delete operator to free pointers as they are removed from the
array.  Before disposing the array, the destructor clears it out
with cut.  This behavior is avoided if the pointers are designated
as external, or shared.  In that case it is entirely up to the
user to free pointers left dangling by cut.  When copying the
array, one must choose whether the copy will share with the
original the objects referenced by the pointers (shallow copy), or
whether the copy will have its own internal duplicates.

<p>
<b>
---------------   WARNING   ---------------
</b>

<p>

The user must provide a specialization of PtrDup() for every
polymorphic class that will instantiate this template.  Failure to
do this may result in unexpected truncation of derived objects.
The template methods use PtrDup() when duplication of objects is
required, but duplicating a polymorphic object requires assistance
from the object itself.  For example, consider class B:

<pre>
class B { public:
virtual B* duplicate(void) const = 0;
};
inline B* PtrDup(const B *b) { return b ? b->duplicate() : 0; }
</pre>

To avoid confusion and mistakes, place the specialization
immediately after the declaration of class B.  If class B does not
have a duplicator use the following specialization instead:

<pre>
inline B* PtrDup(const B *b) {
if (b) throw sxUnimplemented("PtrDup","class B has no duplicator");
else return 0;
}
</pre>

</BLOCKQUOTE>
<DL>

<A NAME="~PtrVec">
<A NAME ="DOC.20.15">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B>  ~PtrVec( void )</B></TT>
<DD>Destructor
<DL></DL><P>
<A NAME="PtrVec">
<A NAME ="DOC.20.1">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B>  PtrVec( bool <!2><A HREF="PtrVec.html#DOC.20.22">internal</A>=true, size_t capacity=0, size_t increment=0 )</B></TT>
<DD>Default constructor.
optionally specify initial capacity, reallocation increment, and
whether the pointers are internal. 
<DL></DL><P>
<A NAME="PtrVec">
<A NAME ="DOC.20.2">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B>  PtrVec( const <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>&, bool <!2><A HREF="PtrVec.html#DOC.20.13">internalize</A> = true )</B></TT>
<DD>Copy constructor.
optionally specify either a shallow copy or an internalized copy
(the default).  The initial capacity is the current capacity of
the duplicated array. 
<DL></DL><P>
<A NAME="copy">
<A NAME ="DOC.20.3">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>&  copy( const <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>&, bool <!2><A HREF="PtrVec.html#DOC.20.13">internalize</A> )</B></TT>
<DD>Copy method. does not decrease the capacity.  The copy is
shallow if internalize is false; otherwise the referenced
objects are duplicated and the copy is internal, in which case
class T must have well-defined copy semantics. 
<DL></DL><P>
<A NAME="operator =">
<A NAME ="DOC.20.4">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A>&  operator =( const <!2><A HREF="PtrVec.html#DOC.20.2">PtrVec</A> &obj )</B></TT>
<DD>Assignment/copy operator. does not decrease the capacity.  This
is not a shallow copy, so class T must have well-defined copy
semantics. 
<DL></DL><P>
<A NAME="()">
<A NAME ="DOC.20.16">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> const  T*& operator  ()( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> ) const </B></TT>
<DD>Efficient array operator (const version): no bounds checking
<DL></DL><P>
<A NAME="()">
<A NAME ="DOC.20.17">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> T*& operator  ()( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> )</B></TT>
<DD>Efficient array operator (non-const version): no bounds checking
<DL></DL><P>
<A NAME="operator []">
<A NAME ="DOC.20.18">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> const  T*&  operator []( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> ) const </B></TT>
<DD>Bounds-checking array operator (const version): throws sxBoundsError
<DL></DL><P>
<A NAME="operator []">
<A NAME ="DOC.20.19">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> T*&  operator []( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> )</B></TT>
<DD>Bounds-checking array operator (non-const version): throws sxBoundsError
<DL></DL><P>
<A NAME="at">
<A NAME ="DOC.20.5">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> T*&  at( size_t <!2><A HREF="PtrVec.html#DOC.20.10">index</A> )</B></TT>
<DD>Bounds-adjusting array operator.  Returns the array
element at the specified index, extending the array as necessary
to bring it within bounds.  Any new elements are set to nil. 
<DL></DL><P>
<A NAME="length">
<A NAME ="DOC.20.20">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  length( void ) const </B></TT>
<DD>Returns current occupied length of array
<DL></DL><P>
<A NAME="entries">
<A NAME ="DOC.20.6">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  entries( void ) const </B></TT>
<DD>Return the number of non-NULL entries in vector.
NOTE: this is different from length(), which also counts NULL pointers.
<DL></DL><P>
<A NAME="append">
<A NAME ="DOC.20.7">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  append( T* )</B></TT>
<DD>Append: efficiently insert given element at end of array.
Avoids redundant initialization of new array element, except for
when a reallocation is required.  Returns the new length. 
<DL></DL><P>
<A NAME="insert">
<A NAME ="DOC.20.8">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  insert( size_t count, size_t offset = 0 )</B></TT>
<DD>Insert new array elements.  

count specifies the number of new elements, and offset specifies
where in the array to insert them.  By default the new elements
are appended.  The new elements are initialized with the nil
pointer value.  offset refers to the end of the array: the first
new element is located at index (length - offset).  Returns the
new length.  Throws sxBoundsError if offset is greater than
length. 
<DL></DL><P>
<A NAME="nextEmpty">
<A NAME ="DOC.20.21">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  nextEmpty()</B></TT>
<DD>Return the index of the next available empty slot
<DL></DL><P>
<A NAME="add">
<A NAME ="DOC.20.9">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  add( T* )</B></TT>
<DD>Add a new array element in the first available empty slot.  
This should be used when the ordering of elements is not
important and empty slots are to be minimized.  Returns the
index of the newly inserted element. 
<DL></DL><P>
<A NAME="index">
<A NAME ="DOC.20.10">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> int  index( const T* )</B></TT>
<DD>Return the index of the given element. (If it exists in
the array, else return -1.) 
<DL></DL><P>
<A NAME="cut">
<A NAME ="DOC.20.11">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  cut( size_t count, size_t offset = 0 )</B></TT>
<DD>Remove array elements.  
count specifies the number of elements to remove, and offset
specifies which elements to remove.  By default elements are
removed from the end of the array.  The unused capacity grows by
this amount.  offset refers to the end of the array: the first
removed element is located at index (length - offset - count).
Returns the new length.  Throws sxBoundsError if (offset+count)
is greater than length. 
<DL></DL><P>
<A NAME="remove">
<A NAME ="DOC.20.12">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> void  remove( size_t offset )</B></TT>
<DD>Removes the element specified by offset.
This is basically a wrapper for the cut method 
<pre>
cut(1, length-offset-1)
<pre>
<DL></DL><P>
<A NAME="internalize">
<A NAME ="DOC.20.13">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> void  internalize( void )</B></TT>
<DD>Replace external pointers with internal
copies of the referenced objects.  class T must have
well-defined copy semantics.  Does nothing if already internal. 
<DL></DL><P>
<A NAME="externalize">
<A NAME ="DOC.20.14">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> void  externalize( void )</B></TT>
<DD>Change status of pointers to external.
Beware that internalize does not undo this; once the pointers
are designated external they cannot just be re-designated as
internal.  Confusion on this point will yield dangling pointers. 
<DL></DL><P>
<A NAME="internal">
<A NAME ="DOC.20.22">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> bool  internal( void ) const </B></TT>
<DD>internal method: returns true if the pointers are internal
<DL></DL><P>
<A NAME="increment_">
<A NAME ="DOC.20.23">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> size_t  increment_</B></TT>
<DD> linear growth increment
<DL></DL><P>
<A NAME="vector_">
<A NAME ="DOC.20.24">
<DT><IMG BORDER=0 SRC=icon2.gif><TT><B> T**  vector_</B></TT>
<DD> dynamic array of pointers
<DL></DL><P></DL>
<hr>
 <DL><DT><B>This class has no child classes.</B></DL>
<DL></DL><P><I><A HREF="aindex.html"> alphabetic index</A></I>  <I><A HREF="HIER.html"> hierarchy of classes</A></I><P><hr>

<img SRC="rule.gif" >
<h6>
&copy;
<A HREF = "http://www.sdss.jhu.edu/ScienceArchive/copyright.html">
Copyright
</A>
The Johns Hopkins University 1999, All Rights Reserved.<br>

<a href="mailto:kunszt@pha.jhu.edu">Peter Z. Kunszt</a>,
<br>
</h6>

</body>
</html>

<P Align=right><I>generated by <A HREF="http://www.zib.de/Visual/software/doc++/index.html">doc++</A></I>
</BODY>
